11.3 Script Utilities

11.3.5 Script Utility Functions

EntryRef *LocateEntry(char *name);
 

Locates the entry named by name in the script. If the entry is not found, NULL is returned. LocateEntry() will accept full-path entry names (see PsyScope User Manual 12.2.3 Entry Syntax 325), so that attributes can be accessed.

char *GetEntryName(char *buffer, EntryRef *ref);
 

Fills in buffer with the (simple) name of the referenced entry. buffer should be at least 256 bytes long.

char *BuildExtendedName(EntryRef *ref);
 

Returns a pointer to the extended name of the referenced entry. The extended name is put into an internal buffer; the contents will be changed when BuildExtendedName() is called again, and this may happen if any of the other Script Utility funtions are called.

int ValidRef(EntryRef *ref);
 

Checks the validity of an entry reference, returning TRUE if it is still valid. (The entry may have been deleted, etc.)

int ValidateRef(EntryRef *ref);
 

Same as ValidRef(), but this function gives the user an error message if ValidRef() fails.

void UntrashRef(EntryRef *vector);
void TrashRef(EntryRef *vector);
 

Secures/unsecures a entry reference. Any number of calls to UntrashEntry() can be made for a given EntryRef *, but each call to UntrashEntry() should be eventually balanced with a call to TrashEntry(). A reference needs to be untrashed only if it is needed accross system event checks or accross trial compilations.

EntryRef *AllocNewEntry(char *name, int reserved);
 

Creates a new entry in the script named by name. The entry is initialized with no tokens or attributes, and it will be added to the end of the script when it is saved. Pass in TRUE for reserved.

EntryRef *AllocNewEntryInBlock(char *name, int reserved, char *block);
 

Like AllocNewEntry(), but the entry is added in the section of the script marked by #> block, if such a section exists. Pass in TRUE for reserved.

EntryRef *AllocNewEntryInBlockWithDef(char *keywd, int reserved, 
	char *block, char *def);
 

Like AllocNewEntryInBlock(), but a content/attribute block defintion may be passed in through def. def should be in the same format as it would be in the script.

void ChangeEntryName(EntryRef *ref, char *newName);
 

Changes the name of the referenced entry in the script. Attribute names may be changed with this function, but inline entry names may not. Existing references to the entry will still be valid.

void DeleteEntry(char *name);
 

Removes an entry from the script. If the entry is not found, ConfigErr is set to RefFailed.

long CountTokens(EntryRef *ref);
 

Returns the number of tokens in the referenced entry, evaluating expressions only to the extent needed to count tokens.

long CountTokensWithVersions(EntryRef *ref, VersionMarker **vm);
 

Same as CountTokens(), but with version tracking.

EntryRef *GetOwnerForReference(EntryRef *ref);
 

For attributes or inline entries, this returns a reference to the owning entry. It returns NULL if the referenced entry is not owned.

int ReferenceSameEntry(EntryRef *ref1, EntryRef *ref2);
 

Returns TRUE of the references are to the same physical entry.

EntryRef *GetThisForReference(EntryRef *ref);
 

Returns the reference which would result in an evaluation of the THIS operator within the referenced entry.

EntryRef *MakeTempEntry(char *definitionString, EntryRef *carry);
 

Creates a temporary entry defined by the given string, with the content and attributes of carry appended to it (carry may be NULL). The reference need not be freed, as usual; when the reference is purged, the entry itself will be deleted. The content of a temporary entry cannot be modified.

EntryRef *MakeHiddenEntry(char *name);
 

Creates a hidden entry. It can be written to and read from, but it is not in the script and cannot be found with LocateEntry(). Once the reference is purged, the entry will be deleted.

EntryRef *LocateAttrib(EntryRef *ref, char *name);
 

EntryRef *LocateOrCreateAttrib(EntryRef *ref, char *name);
 

EntryRef *LocateIndexedAttrib(EntryRef *ref, int which);
 

EntryRef *AddAttribType(EntryRef *ref, char *name, int reserved);
 

void KillAttribType(EntryRef *ref, char *name);
 

void MoveAttribute(EntryRef *dest, EntryRef *src, char *aname, 
	int destructive);
 

char *GetATok(EntryRef *ref, int which);
 

EntryRef *GetAReference(EntryRef *ref, int which)
 

char *GetATokWithInfoAndVersions(EntryRef *ref, int which, TokInfo *info,
	VersionMarker **verPtr);
#define GetATokWithInfo(ref, which, info) \
	GetATokWithInfoAndVersions(ref, which, info, 0L)
#define GetATokWithVersions(ref, which, versions) \
	GetATokWithInfoAndVersions(ref, which, 0L, versions)
 

Like GetATok(), but inheritance information is put into info (if it is non-NULL) and version marking information is appended to *verPtr (if verPtr is non-NULL). See also "11.3.4 Inheritance" and "11.3.3 Version Markers".

EntryRef *GetAReferenceWithInfoAndVersions(EntryRef *ref, int which, 
	TokInfo *info, VersionMarker **verPtr);
#define GetAReferenceWithInfo(ref, which, info) \
	GetAReferenceWithInfoAndVersions(ref, which, info, 0L)
#define GetAReferenceWithVersions(ref, which, version) \
	GetAReferenceWithInfoAndVersions(ref, which, 0L, version)
 

See GetAReference() and GetATokWithInfoAndVersions().

Ptr GetATokOrRefWithInfoAndVersions(EntryRef *ref, int which, int *type,
	TokInfo *info, VersionMarker **verPtr);
#define GetATokOrRef(ref, which, type) \
	GetATokOrRefWithInfoAndVersions(ref, which, type, 0L, 0L)
#define GetATokOrRefWithInfo(ref, which, type, info) \
	GetATokOrRefWithInfoAndVersions(ref, which, type, info, 0L)
#define GetATokOrRefWithVersions(ref, which, type, vm) \
	GetATokOrRefWithInfoAndVersions(ref, which, type, 0L, vm)
 

This is the most general token-getting function. *type should be -1 on input; it will be set to string_tok_info or reference_tok_info on return, specifying wether a char * or EntryRef * was returned. If info is non-NULL, then it is filled in with inheritance information (see "11.3.4 Inheritance"). If verPtr is non-NULL, version marking information is appended to *verPtr (see "11.3.3 Version Markers").

long GetANumberWithVersions(EntryRef *ref, int which, long def,
	VersionMarker **vm);
#define GetANumber(ref, which, def) \
	GetNumberWithVersions(ref, which, def, 0L)
 

Gets the whichth token (using GetATokWithVersions()) and converts it to a number. If there is no whichth token, or if it does not convert to a number, then def is passed back.

void SetATok(EntryRef *ref, int which, char *newTok);
 

Finds the whichth token in the referenced entry and replaces it with newTok. which starts from 0. Only literal expressions may be replaced; attempting to replace a token that is an operation sentence will return an error to the user and set ConfigErr to CantSetTok. If there is no whichth token, no changes are made and ConfigErr is set to ReplacePastEnd.

void SetInlineEntry(EntryRef *ref, int which, char *name);
 

Replaces a literal expressionwith an inline entry definition with the given name.

void AddATok(EntryRef *ref, int which, int depth, char *newTok);
 

Adds newTok just before the whichth token in the referenced entry. which starts from 0. If which is greater than or equal to the number of tokens, a new token is added to the end of the list.

If depth is DEEP, the new token is placed as "deep" as possible following token references. If depth is SHALLOW, it is placed as "shallow" as possible.

void SetOrAddATok(EntryRef *ref, int which, char *newTok);
 

Attempts to set the token using SetATok(); if ConfigErr gets set to ReplacePastEnd, the token is added using AddATok(ref, which, DEEP, newTok).

void KillATok(EntryRef *ref, int which, int killVersion);
 

Removes the expression generating the whichth token from the refernced entry. which starts from 0. The whichth token has to be derived from literal expression if killVersion is KILL_LIT; if the whichth token is from a non-literal expression and KILL_LIT is used, no expressions are deleted, the user is notified, and ConfigErr is set toCantSetTok.

If killVersion is KILL_ALL, any type of expression may be deleted -- even if the expression is responsibel for multiple tokens.

If there is no whichth token, then no changes are made and ConfigErr is set to ReplacePastEnd.

void KillAllToksAfter(EntryRef *ref, int which, int killVersion);
 

Kills expressions yeilding tokens past and including the whichth token. killVersion is as with KillATok().

void EmptyContentLine(EntryRef *ref);
 

Deletes all expressions from the content line of the referenced entry.

char *GetAttribTok(EntryRef *ref, char *attrib, int which);
char *GetAttribTokWithVersions(EntryRef *ref, char *keyword, int which, 
	VersionMarker **vm);
void SetAttribTok(EntryRef *ref, char *attrib, int which, 
	char *newTok);
void AddAttribTok(EntryRef *ref, char *attrib, int which, int depth, 
	char *newTok);
void KillAttribTok(EntryRef *ref, char *attrib, int which, 
	int killVersion); 
long GetAttribNumberWithVersions(EntryRef *ref, char *attrib, 
	int which, long defval, VersionMarker **vm);
#define GetAttribNumber(ref, attr, which, def) \
	GetNumberWithVersions(ref, attr, which, def, NULL)
 

See the corresponding non-attribute versions (i.e. same function name, but without Attrib) above. Instead of working on ref, these functions look for an attribute of the referenced entry named attrib and work on the attribute. If the attribute is not found, the user is notified and ConfigErr is set to AttribNotFound.

char *AllTokOneStr(char *name, char *buffer, long buffsize);
 

Takes an entry name in name and dumps all of the values from the content line of the entry into buffer. Separate tokens with spaces in them will be quoted within buffer.

int EntriesToBufferWithVersions(EntryRef *ref, char *buffer, int pretty,
	long bufsize, VersionMarker **);
  #define min_prettiness (-1) /* Quote everything */
  #define med_prettiness	 0		    /* Always quote when needed */
  #define max_prettiness	 1    /* Don't quote if it's just one token */
#define EntriesToBuffer(ref, buffer, pretty, size) \
	EntriesToBufferWithVersions(ref, buffer, pretty, size, 0L)
 

Like AllTokOneStr(), but an entry reference is specified instead, and more control is available over the format of the string through pretty.

int EntriesToStringWithVersions(EntryRef *ref, infstr inf, int pretty, 
	VersionMarker **versions);
 

Like EntriesToBufferWithVersions(), but for infinite strings (see ??).

char *AttribsToBuffer(EntryRef *ref, char *attrib, char *buffer, 
	long bufsize);
 

Like EntriesToBuffer(), but the tokens are taken from an attribute of the referenced entry named attrib. If the attribute is not found, the user is notified and ConfigErr is set to AttribNotFound.

int IsInListOfToksWithVersions(EntryRef *in_ref, char *tok, 
	VersionMarker **vm);
#define IsInListOfToks(ir, t) IsInListOfToksWithVersions(ir, t, 0L)
 

Looks for a token with value tok in the content of the referenced entry. If such a token is found, its position in the token list will be returned, indexed from 1 instead of the usual 0. If no matching token is found, 0 is returned. Version markers are appened to *vm if vm is non-NULL (see "11.3.3 Version Markers").

int IsInListOfRefsWithVersions(EntryRef *in_ref, EntryRef *ref, 
	VersionMarker **vm);
#define IsInListOfRefs(ir, r) IsInListOfRefsWithVersions(ir, r, 0L)
extern int validateRefList;
 

Like IsInListOfToks(), but for searching for a reference-valued token. This function will delete tokens with invalid references values without warning unless the validateRefList flag is turned off.

TokenValue *GetToksAndRefsWithVersions(EntryRef *ref, int *size, 
	VersionMarker **vm);
#define GetToksAndRefs(ref, size) \
	GetToksAndRefsWithVersions(ref, size, 0L)
 

Resolves all tokens in the content of the referenced entry and returns a new TokenValue array. *size is set to the size of the returned array. If vm is non-NULL, version markers are appended to *vm (see "11.3.3 Version Markers"). See also "11.3.2 Token Values".

On return, *size == 0 does not imply that the return value is NULL. This can happen if the content of the referenced token is empty.

TokenValue *GetToksWithVersions(EntryRef *ref, int *size, 
	VersionMarker **vm);
#define GetToks(r, s) GetToksWithVersions(r, s, 0L)
 

Like GetToksAndRefsWithVersions(), except if a reference-valued token found, ConfigErr is set to DirAccess and the user is notified. Depending on the user's response, other valid tokens may or may not be returned.

TokenValue *GetRefsWithVersions(EntryRef *ref, int *size, 
	VersionMarker **vm);
#define GetRefs(r, s) GetRefsWithVersions(r, s, 0L)
 

Like GetToksAndRefsWithVersions(), except if an entry referenced by token cannot befound, ConfigErr is set to RefFailed and the user is notified. Depending on the user's response, other valid tokens may or may not be returned.

TokenValue *GetValidRefsWithVersions(EntryRef *ref, int *count,
	VersionMarker **vm);
 

Like GetRefsWithVersions(), but no error is given if an invaid reference is encountered; instead, the invalid reference is deleted from the script.

TokenValue *ExpandTokenValueList(TokenValue *toks, int curCount, 
	void *data, int type, TokInfo *info);
#define MakeSingleTokenValue(v, i) \
	ExpandTokenValueList(0L, 0, v, string_tok_info, i)
#define AddTokenValueString(toks, count, str) \
	ExpandTokenValueList(toks, count, str, string_tok_info, 0L)
#define AddTokenValueRef(toks, count, ref) \
	ExpandTokenValueList(toks, count, ref, reference_tok_info, 0L)
 

Add a new TokenValue record to the given array and returns a pointer to the expanded array. If toks is NULL, a new array is created. curCount should be the starting size of the array; the new size will be curCount + 1.

type should be string_tok_info or ref_tok_info. data should be a char * or EntryRef *, depending on type. info is optional; a copy is made if info is supplied, so that info should still be freed.

int TokenValuesToInfStrWithVersions(TokenValue *toks, int count, 
	infstr inf, int pretty, VersionMarker **vm);
#define TokenValuesToInfStr(t, c, i, p) \
	TokenValuesToInfStrWithVersions(t, c, i, p, 0L)
 

Like EntriesToStringWithVersions(), but an array of tokens is passed in instead of an entry reference.

extern void FreeToks(TokenValue *toks, int count);
 

Frees structure returned by GetToks() et al. See also "11.3.2 Token Values".

TokenValue *DuplicateToks(TokenValue *toks, int count);
 

Returns a copy of toks, which has to be freed separately.

int GetAnExpression(EntryRef *ref, int which, char *buffer, int buflen);
 

void SetAnExpression(EntryRef *ref, int which, char *expr);
 

int GetAllExpressions(EntryRef *ref, ECSList strings);
 

void SetAllExpressions(EntryRef *ref, ECSList strings);
 

int CountExpressions(EntryRef *ref);
 

void CopyEntry(EntryRef *to, EntryRef *from);
 

int CheckExpressionValidity(char *expr, char *reasonBuffer);
 

int IsInListOfExpressions(EntryRef *ref, char *expr);
 

EntryRef *LocateAttribFromInherit(InheritRec *inh, char *name);
 

Attempts to locate an inherited attribute named name given the inheritance information. See also "11.3.4 Inheritance".

void FreeTokInfo(TokInfo *info);
 

Frees inheritance information in info. See also "11.3.4 Inheritance".

EntryRef *GetActualLocation(TokInfo *info);
 

Returns a reference to the entry which will be the first searched for inherited attributes.

EntryRef *GetActualLocationFromInherit(InheritRec *inh);
 

Same as GetActualLocation(), but the InheritRec pointer is passed directly.

int EqualInheritRecs(InheritRec *one, InheritRec *two);
 

Returns TRUE if the inheritance paths are the same.

InheritRec *AppendInheritRecs(InheritRec *one, InheritRec *appendToOne);
 

Returns an inheritance path that is one followed by appendToOne. one is automaticallyfreed, but appendToOne is not.

InheritRec *PreceedInheritsWithRef(InheritRec *inh, EntryRef *ref);
 

Adds one reference to the beginning of the inheritance path; inh is automatically freed.

int SameVersions(VersionMarker *vm);
 

Returns TRUE if the script is unchanged from the state information stored in vm. See also "11.3.3 Version Markers".

VersionMarker *AppendVersionMarkers(VersionMarker *dest, 
	VersionMarker *src);
 

Returns a VersionMarker array that is dest followed by src. dest is automatically freed, but src is not.

Appends the version of the referenced entry to vm and returns a new VersionMarker array; vm is automatcially freed. If the referenced entry is already included in vm's state information, then vm will be returned without modification.

The state information about ref that is kept in the new array includes attributes owned by the referenced entry, expressions in content of the entry (but not the content of the attributes), and the list access state of the entry.

VersionMarker *AppendOneExprVersion(VersionMarker *vm, EntryRef *ref);
 

Like AppendOneVersion(), except that the list access state of the referenced entry is ignored.

int GetEntryVersion(EntryRef *ref);
 

Returns a number representing the "version" of the referenced entry. This number will change if any attributes are added to the entry, or if any expression in the content of the entry is modified.

long GetEffectiveVersion(EntryRef *ref, int accessed);
 

Like GetEntryVersion(), except that this number is also influenced by the access state of the tokens in the referenced entry's content line. When the current item is changed, this number will change, but it will be the same whenever a particular item is current (all else constant).

ChangesRecord NewChangesRecord(void);
 

void StartRememberingChanges(ChangesRecord changes);
 

void StopRememberingChanges(ChangesRecord changes);
 

ChangesRecord CurrentChangesRecord(void);
 

void DisposeChanges(ChangesRecord changes);
 

void ForgetChanges(ChangesRecord changes);
 

void UndoChanges(ChangesRecord changes);
 

ChangesRecord UndoChangesWithRedo(ChangesRecord changes);
 

int GetErrMask(int errCode);
 

11.3.5.1 - EntryRefs

11.3.5.2 - Attributes

11.3.5.3 - Tokens

11.3.5.4 - Token Value Arrays

11.3.5.5 - Expressions

11.3.5.6 - Inheritance

11.3.5.7 - Version Marking

11.3.5.8 - Script Changes Recording

11.3.5.9 - Masking Error Reports

Generated with CERN WebMaker