mata_mlib.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

{smcl}
{* 31mar2005}{...}
{cmd:help mata mlib}
{hline}
{* index libraries}{...}
{* index mata tt}{...}
{* index mlib tt}{...}
{* index .mata file}{...}
{* index .mlib library files}{...}

{title:Title}

{p 4 4 2}
{bf:[M-3] mata mlib -- Create function library}


{title:Syntax}

{p 8 16 2}
: {cmd:mata mlib create}
{it:libname}{bind:          }
[{cmd:,} 
{cmd:dir(}{it:path}{cmd:)} 
{cmd:replace}
]

{p 8 16 2}
: {cmd:mata mlib add}{bind:   }
{it:libname}
{it:fcnlist}{cmd:()}
[{cmd:,} 
{cmd:dir(}{it:path}{cmd:)} 
]

{p 8 17 2}
: {cmd:mata mlib index}

{p 8 17 2}
: {cmd:mata mlib} {cmdab:q:uery}


{p 4 4 2}
where {it:fcnlist}{cmd:()} is a {it:namelist} containing only function names, such 
as 

		{it:fcnlist}{cmd:()} examples
		{hline 41}
		{cmd:myfunc()}
		{cmd:myfunc()} {cmd:myotherfunc()} {cmd:foo()}
		{cmd:f*() g*()}
		{cmd:*()}
		{hline 41}
		see {bf:{help m3_namelists:[M-3] namelists}} 


{p 4 4 2}
and where {it:libname} is the name of a library.  The {it:libname} must start
with the letter {cmd:l} and does not contain the .mlib suffix.  Examples of
{it:libnames} include

		{it:libname}           corresponding filename
		{hline 41}
		{cmd:lmath}                  {cmd:lmath.mlib}
		{cmd:lmoremath}              {cmd:lmoremath.mlib}
		{cmd:lnjc}                   {cmd:lnjc.mlib}
		{hline 41}

{p 4 4 2}
In addition, {it:libnames} that begin with the letters {cmd:lmata}, 
such as {cmd:lmatabase}, are reserved for the names of official libraries.

{p 4 4 2}
This command is for use in Mata mode following Mata's colon prompt.
To use this command from Stata's dot prompt, type

		. {cmd:mata: mata mlib} ...


{title:Description}

{p 4 4 2}
{cmd:mata} {cmd:mlib} creates, adds to, and causes Mata to index
.mlib files, which are libraries containing the object-code 
functions.

{p 4 4 2}
{cmd:mata mlib create} creates a new, empty library.

{p 4 4 2}
{cmd:mata mlib add} adds new members to a library.

{p 4 4 2}
{cmd:mata mlib index} causes Mata to build a new list of libraries to be 
searched.

{p 4 4 2}
{cmd:mata mlib query} lists the libraries to be searched.

{p 4 4 2}
A library may contain up to 500 functions.


{title:Options}

{p 4 8 2}
{cmd:dir(}{it:path}{it:)} specifies the directory (folder) into which the file
    should be written.  {cmd:dir(.)} is the default, meaning that 
    if {cmd:dir()} is not specified, the file is written
    into the current (working) directory.  {it:path} may be a directory name
    or may be the sysdir shorthand {cmd:STATA}, {cmd:UPDATES}, {cmd:BASE},
    {cmd:SITE} {cmd:PLUS}, {cmd:PERSONAL}, or {cmd:OLDPLACE}; see 
    {bf:{help sysdir:[P] sysdir}}.
    {cmd:dir(PERSONAL)} is recommended.

{p 4 8 2}
{cmd:replace} specifies that the file may be replaced if it already exists.


{title:Remarks}

{p 4 4 2}
Remarks are presented under the headings

	{bf:Background}
	{bf:Outline of the procedure for dealing with libraries}
	{bf:Creating a .mlib library}
	{bf:Adding members to a .mlib library}
	{bf:Listing the contents of a library}
	{bf:Making it so Mata knows to search your libraries}
	{bf:Advice on organizing your source code}

{p 4 4 2}
In addition, see {bf:{help m1_how:[M-1] how -- How Mata works}} for an explanation of
object code.


{title:Background}


{p 4 4 2}
.mlib files contain the object code for one or more functions.
Functions which happen to be stored in libraries are called 
library functions, and 
Mata's library functions are also stored in .mlib libraries.
You can create your own libraries, too.

{p 4 4 2}
Mata provides two ways to store object code:

{p 8 12 2}
    1.  In a .mo file, which contains the code for a single function.

{p 8 12 2}
    2.  In a .mlib library file, which may contain the code for
        up to 500 functions.

{p 4 4 2}
.mo files are easier to use and work just as well as .mlib
libraries; see {bf:{help mata_mosave:[M-3] mata mosave}}.  .mlib
libraries, however, are easier to distribute to others when you have lots of
functions, because they are combined into a single file.


{title:Outline of the procedure for dealing with libraries}

{p 4 4 2}
Working with libraries is easy:

{p 8 12 2}
    1.  First, choose a name for your library.  We will choose the 
        name {cmd:lpersonal}.

{p 8 12 2}
    2.  Next, create an empty library using the {cmd:mata} {cmd:mlib}
        {cmd:create} command.

{p 8 12 2}
    3.  After that, you can add new members to the library at any time,
        using {cmd:mata} {cmd:mlib} {cmd:add}.

{p 4 4 2}
.mlib libraries contain object code, not the 
original source code, so you need to keep track of the source code yourself.
In addition, if you want to update the object code in a function stored in a
library, you must recreate the entire library; there is no way to
replace or delete a member once it is added.

{p 4 4 2}
We begin by showing you the mechanical steps, and then we will tell you
how we manage libraries and source code.


{title:Creating a .mlib library}

{p 4 4 2}
If you have not read {bf:{help mata_mosave:[M-3] mata mosave}}, 
please do so.

{p 4 4 2}
To create a new, empty library named {cmd:lpersonal.mlib} in the current 
directory, type 

	: {cmd:mata mlib create lpersonal}
	file lpersonal.mlib created

{p 4 4 2}
If {cmd:lpersonal.mlib} already exists and you want to replace it, either 
erase the existing file first, or type 

	: {cmd:mata mlib create lpersonal, replace}
	file lpersonal.mlib created

{p 4 4 2}
To create a new, empty library named {cmd:lpersonal.mlib} in your 
{cmd:PERSONAL} {bf:{help sysdir:[P] sysdir}} directory, type 

	: {cmd:mata mlib create lpersonal, dir(PERSONAL)}
	file c:\ado\personal\lpersonal.mlib created

{p 4 4 2}
or 

	: {cmd:mata mlib create lpersonal, dir(PERSONAL) replace}
	file c:\ado\personal\lpersonal.mlib created


{title:Adding members to a .mlib library}

{p 4 4 2}
Once a library exists, whether you have just created it and it is 
empty, or it already existed and contains some functions, 
you can add new functions to it by typing 

	: {cmd:mata mlib add} {it:libname} {it:fcnname}{cmd:()}

{p 4 4 2}
So, if we wanted to add function {cmd:example()} to library {cmd:lpersonal.mlib}, 
we would type 

	: {cmd:mata mlib add lpersonal example()}
	(1 function added)

{p 4 4 2}
In doing this, we do not have to say where {cmd:lpersonal.mlib} is stored;
Mata searches for it along the adopath.

{p 4 4 2}
Before you can add {cmd:example()} to the library, however, you 
must compile it:

	: {cmd:function} {cmd:example}{cmd:(}...{cmd:)}
	> {cmd:{c -(}}
	>        ...
	> {cmd:{c )-}}

	: {cmd:mata mlib add lpersonal example()}
	(1 function added)

{p 4 4 2}
You can add many functions to a library in a single command:

	: {cmd:mata mlib add lpersonal example2() example3()}
	(2 functions added)

{p 4 4 2}
You can add all the functions currently in memory by typing 

	: {cmd:mata mlib add lanother *()}
	(3 functions added)

{p 4 4 2}
In the above example, we added to {cmd:lanother.mlib} because 
we had already added {cmd:example()}, {cmd:example2()}, and 
{cmd:example3()} to {cmd:lpersonal.mlib} and trying to add them again 
would result in an error.  (Before adding {cmd:*()}, we could 
verify that we are adding what we want to add by typing 
{cmd:mata} {cmd:describe} {cmd:*()}; see help 
{bf:{help mata_describe:[M-3] mata describe}}.)


{title:Listing the contents of a library}

{p 4 4 2}
Once a library exists, you can list its contents (the names of the 
functions it contains) by typing 

	: {cmd:mata describe using} {it:libname}

{p 4 4 2}
In our case, we would type 

	: {cmd:mata describe using lpersonal}

              {txt}# bytes   type                       name and extent
        {hline 69}
        {res}           24   {txt}auto transmorphic matrix   {res}example{txt}()
        {res}           24   {txt}auto transmorphic matrix   {res}example2{txt}()
        {res}           24   {txt}auto transmorphic matrix   {res}example3{txt}()
        {hline 69}{txt}

{p 4 4 2}
{cmd:mata} {cmd:describe} usually lists the contents of memory, but 
{cmd:mata} {cmd:describe} {cmd:using} lists the contents of a library.


{title:Making it so Mata knows to search your libraries}

{p 4 4 2}
Mata automatically finds the .mlib libraries on your computer.  It does
this when Mata is invoked for the first time during a session.  Thus
everything is automatic except that Mata will know nothing about any new
libraries created during the Stata session, so after creating a new library,
you must tell Mata about it.  You do this by asking Mata to rebuild its
library index:

	: {cmd:mata mlib index}

{p 4 4 2}
Note that you do not specify the name of your new library.  That name 
does not matter because Mata rebuilds its entire library index.  

{p 4 4 2}
You can issue the {cmd:mata mlib index} command right after creating the
new library

	: {cmd:mata mlib create lpersonal, dir(PERSONAL)}

	: {cmd:mata mlib index}

{p 4 4 2}
or after you have created and added to the library:

	: {cmd:mata mlib create lpersonal, dir(PERSONAL)}

	: {cmd:mata mlib add *()}

	: {cmd:mata mlib index}

{p 4 4 2}
It does not matter.  Mata does not need to rebuild its index after a 
known library is updated; Mata only needs to be told to rebuild 
when a new library is added during the session.  


{title:Advice on organizing your source code}

{p 4 4 2}
Say you wish to create and maintain {cmd:lpersonal.mlib}.  Our preferred 
way is to use a do-file:

	{hline 50} lpersonal.do {hline 5}
	{cmd}mata:
	mata clear

	{txt}{it:function definitions appear here}{cmd}

	mata mlib create lpersonal, dir(PERSONAL) replace
	mata mlib add *()
	mata mlib index
	end{txt}
	{hline 50} lpersonal.do {hline 5}

{p 4 4 2}
This way, 
all we have to do to create or recreate the library is 
enter Stata, change to the directory containing our source code, and 
type

	. {cmd:do lpersonal}

{p 4 4 2}
For large libraries, we like to put the source code for different parts in
different files:

	{hline 50} lpersonal.do {hline 5}
	{cmd}mata: mata clear

	do function1.mata
	do function2.mata
	{txt}...{cmd}

	mata:
	mata mlib create lpersonal, dir(PERSONAL) replace
	mata mlib add *()
	mata mlib index
	end{txt}
	{hline 50} lpersonal.do {hline 5}

{p 4 4 2}
The function files contain the source code, which might include
one function, or it might include more than one function if the primary function 
had subroutines:

	{hline 49} function1.mata {hline 5}
	{cmd:mata:}
	{it:function definitions appear here}
	{cmd:end}
	{hline 49} function1.mata {hline 5}

{p 4 4 2}
We name our component files ending in {cmd:.mata}, but they are still just 
do-files.


{title:Also see}

{p 4 13 2}
Manual:  {hi:[M-3] mata mlib}

{p 4 13 2}
Online:  help for 
{bf:{help mata_mosave:[M-3] mata mosave}};
{bf:{help m3_intro:[M-3] intro}}
{p_end}