audk/ShellPkg/Library/UefiShellLevel1CommandsLib/UefiShellLevel1CommandsLib.uni

<EFBFBD><EFBFBD>// /**
//
// Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
// This program and the accompanying materials
// are licensed and made available under the terms and conditions of the BSD License
// which accompanies this distribution. The full text of the license may be found at
// http://opensource.org/licenses/bsd-license.php
//
// THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
// WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
//
// Module Name:
//
// UefiShellLevel2CommandsLib.uni
//
// Abstract:
//
// String definitions for UEFI Shell 2.0 level 1 commands
//
//
// **/

/=#

#langdef   en-US "en-USlish"

#string STR_NO_SCRIPT             #language en-US "%EError. %NThe command '%B%s%N' is incorrect outside of a script.\r\n"
#string STR_GEN_PROBLEM           #language en-US "%EError. %NThe argument '%B%s%N' is incorrect.\r\n"
#string STR_GEN_PROBLEM_VAL       #language en-US "%EError. %NThe argument '%B%s%N' has incorrect value.\r\n"
#string STR_GEN_PROBLEM_SCRIPT    #language en-US "%EError. %NThe argument '%B%s%N' is incorrect. Line: %d\r\n"
#string STR_GEN_INV_VAR           #language en-US "%EError. %NThe script's Indexvar '%B%s%N' is incorrect.\r\n"
#string STR_GEN_TOO_FEW           #language en-US "%EError. %NToo few arguments specified.\r\n"
#string STR_GEN_TOO_MANY          #language en-US "%EError. %NToo many arguments specified.\r\n"

#string STR_TEXT_AFTER_THEN       #language en-US "%EError. %NThen cannot be followed by anything.\r\n"
#string STR_SYNTAX_AFTER_BAD      #language en-US "%EError. %NSyntax after %s incorrect.\r\n"
#string STR_SYNTAX_IN             #language en-US "%EError. %NSyntax after analyzing %s.\r\n"
#string STR_SYNTAX_NO_MATCHING    #language en-US "%EError. %NNo matching '%B%s%N' for '%B%s%N' statement found. Line: %d.\r\n"
#string STR_INVALID_BINOP         #language en-US "%EError. Binary operator not found first in '%B%s%N'.\r\n"
#string STR_SYNTAX_STARTING       #language en-US "%EError. %NSyntax after %s.\r\n"

#string STR_STALL_FAILED          #language en-US "%EError. %NBootService Stall() failed with %r.\r\n"

#string STR_GET_HELP_EXIT         #language en-US ""
".TH exit 0 "exits the script or shell"\r\n"
".SH NAME\r\n"
"Exits the UEFI Shell or the current script.\r\n"
".SH SYNOPSIS\r\n"
"exit [/b] [exit-code]\r\n"
".SH OPTIONS\r\n"
"/b          Indicates that only the current UEFI shell script should be \r\n"
"            terminated. Ignored if not used within a script.\r\n"
"exit-code   If exiting a UEFI shell script, the value that will be placed\r\n"
"            into the environment variable lasterror. If exiting an instance\r\n"
"            of the UEFI shell, the value that will be returned to the caller.\r\n"
"            If not specified, then 0 will be returned.\r\n"
".SH DESCRIPTION\r\n"
"This command exits the UEFI Shell or, if /b is specified, the current script.\r\n"
".SH RETURNVALUES\r\n"
"0           Exited normally\r\n"
"exit-code   The value specified as an option.\r\n"

#string STR_GET_HELP_FOR          #language en-US ""
".TH for 0 "starts a for loop"\r\n"
".SH NAME\r\n"
"Starts a loop based on for syntax.\r\n"
".SH SYNOPSIS\r\n"
"for %indexvar in set\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"endfor\r\n"
"for %indexvar run (start end [step])\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"endfor\r\n"
".SH DESCRIPTION\r\n"
"The for command executes one or more commands for each item in a set of items. The set may be text strings or filenames or a mixture of both, separated by spaces (if not in a quotation). If the length of an element in the set is between 0 and 256, and if the string contains wildcards, the string will be treated as a file name containing wildcards, and be expanded before command is executed.\r\n"
"If after expansion no such files are found, the literal string itself is kept. Indexvar is any alphabet character from 'a' to 'z' or 'A' to 'Z', and they are case sensitive. It should not be a digit (0-9) because %digit will be interpreted as a positional argument on the command line that launches the script. The namespace for index variables is separate from that for environment variables, so if indexvar has the same name as an existing environment variable, the environment variable will remain unchanged by the for loop.\r\n"
"Each command is executed once for each item in the set, with any occurrence of %indexvar in the command replacing with the current item. In the second format of for &  endfor statement, indexvar will be assigned a value from start to end with an interval of step. start and end can be any integer whose length is less than 7 digits excluding sign, and it can also applied to step with one exception of zero. step is optional, if step is not specified it will be automatically determined by following rule, if start <= end then step = 1, otherwise step = -1. start, end and step are divided by space.\r\n"
".SH EXAMPLES\r\n"
"#\r\n"
"# Sample for loop - listing all .txt files\r\n"
"#\r\n"
"echo -off\r\n"
"for %a in *.txt\r\n"
"echo %a exists\r\n"
"endfor\r\n"
"If in current directory, there are 2 files named file1.txt and file2.txt, \r\n"
"the output of the sample script will be:\r\n"
"Sample1> echo -off\r\n"
"file1.txt exists\r\n"
"file2.txt exists\r\n"
"Theoretically it is legal for 2 nested for commands to use the same alphabet \r\n"
"letter as their index variable, for instance, a.\r\n"
"#\r\n"
"# Sample for loop from 1 to 3 with step 1\r\n"
"#\r\n"
"echo -off\r\n"
"for %a run (1 3)\r\n"
"echo %a\r\n"
"endfor\r\n"
"#\r\n"
"# Sample for loop from 3 down to 1 with step -1\r\n"
"#\r\n"
"echo -off\r\n"
"for %a run (3 1 -1)\r\n"
"echo %a\r\n"
"endfor\r\n"
"#\r\n"
"# Sample for loop - 2 nested for using same index variable\r\n"
"#\r\n"
"echo -off\r\n"
"for %a in value1 value2\r\n"
"for %a in value3 value4\r\n"
"echo %a\r\n"
"endfor\r\n"
"endfor\r\n"
"When processing first for and before seeing the endfor, the index variable %a has\r\n"
"the value "value1", so in second for, the %a has been already defined and it will be\r\n"
"replaced with the current value of %a. The string after substitution becomes for\r\n"
"value1 in value3 value4, which is not a legal for command. Thus only when the\r\n"
"value of %a is also a single alphabet letter, the script will be executed without error.\r\n"
"If 2 independent for commands use the same index variable, when the second for is\r\n"
"encountered, the first for has already freed the variable so there'll be no problem in\r\n"
"this case.\r\n"

#string STR_GET_HELP_ENDFOR       #language en-US ""
".TH endfor 0 "ends a for loop"\r\n"
".SH NAME\r\n"
"Ends a 'for' loop.\r\n"
".SH SYNOPSIS\r\n"
"Please see 'for' for usage.\r\n"
".SH EXAMPLES\r\n"
"Please see 'for' for examples.\r\n"

#string STR_GET_HELP_GOTO         #language en-US ""
".TH goto 0 "moves to a label"\r\n"
".SH NAME\r\n"
"moves around the point of execution in a script.\r\n"
".SH SYNOPSIS\r\n"
" goto label\r\n"
".SH DESCRIPTION\r\n"
"The goto command directs script file execution to the line in the script file after the given label. The command is not supported from the interactive shell. A label is a line beginning with a colon (:). It can appear either after the goto command, or before the goto command. The search for label is done forward in the script file, from the current file position. If the end of the file is reached, the search resumes at the top of the file and continues until label is found or the starting point is reached. If label is not found, the script process terminates and an error message is displayed. If a label is encountered but there is no goto command executed, the label lines are ignored. Using goto command to jump into another for loop is not allowed, but jumping into an if statement is legal.\r\n"
".SH EXAMPLES\r\n"
"  # This is a script\r\n"
"  goto Done\r\n"
"  & \r\n"
"  :Done\r\n"
"  cleanup.nsh\r\n"

#string STR_GET_HELP_ENDIF        #language en-US ""
".TH endif 0 "ends an if block"\r\n"
".SH NAME\r\n"
"Ends the block of a script controlled by an 'if' statement.\r\n"
".SH SYNOPSIS\r\n"
"See 'if' for usage.\r\n"
".SH EXAMPLES\r\n"
"See 'if' for examples.\r\n"

#string STR_GET_HELP_IF           #language en-US ""
".TH if 0 "controls the execution of a block of a script"\r\n"
".SH NAME\r\n"
"Controls which script commands will be executed based on provided conditional expressions.\r\n"
".SH SYNOPSIS\r\n"
"if [not] exist filename then\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"[else\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"]\r\n"
"endif\r\n"
"if [/i] [not] string1 == string2 then\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"[else\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"]\r\n"
"endif\r\n"
"if [/i][/s] ConditionalExpression then\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"[else\r\n"
"command [arguments]\r\n"
"[command [arguments]]\r\n"
"& \r\n"
"]\r\n"
"Endif\r\n"
".SH DESCRIPTION\r\n"
"The if command executes one or more commands before the else or endif\r\n"
"commands, if the specified condition is true; otherwise commands between else (if\r\n"
"present) and endif are executed.\r\n"
"In the first usage of if, the exist condition is true when the file specified by filename\r\n"
"exists. The filename argument may include device and path information. Also wildcard\r\n"
"expansion is supported by this form. If more than one file matches the wildcard\r\n"
"pattern, the condition evaluates to TRUE.\r\n"
"In the second usage, the string1 == string2 condition is true if the two strings are\r\n"
"identical. Here the comparison can be case sensitive or insensitive, it depends on the\r\n"
"optional switch /i. If /i is specified, it will compare strings in the case insensitive\r\n"
"manner; otherwise, it compares strings in the case sensitive manner.\r\n"
"In the third usage, general purpose comparison is supported using expressions\r\n"
"optionally separated by and or or. Since < and > are used for redirection, the\r\n"
"expressions use common two character (FORTRAN) abbreviations for the operators\r\n"
"(augmented with unsigned equivalents):\r\n"
"Expressions\r\n"
"Conditional expressions are evaluated strictly from left to right. Complex conditionals\r\n"
"requiring precedence may be implemented as nested ifs.\r\n"
"The expressions used in the third usage have the following syntax:\r\n"
"conditional-expression := expression |\r\n"
"expression and expression\r\n"
"expression or expression\r\n"
"expression := expr |\r\n"
"not expr\r\n"
"expr := item binop item |\r\n"
"boolfunc(string)\r\n"
"item := mapfunc(string) |\r\n"
"string\r\n"
"mapfunc := efierror | pierror | oemerror\r\n"
"boolfunc := isint | exists | available | profile\r\n"
"binop := gt | lt | eq | ne | ge | le | == | ugt | ult | uge | ule\r\n"
"Comparisons\r\n"
"By default, comparisons are done numerically if the strings on both sides of the\r\n"
"operator are numbers (as defined below) and in case sensitive character sort order\r\n"
"otherwise. Spaces separate the operators from operands.\r\n"
"The /s option forces string comparisons and the /i option forces case-insensitive\r\n"
"string comparisons. If either of these is used, the signed or unsigned versions of the\r\n"
"operators have the same results. The /s and /i apply to the entire line and must\r\n"
"142 Version 2.0\r\n"
"appear at the start of the line (just after the if itself). The two may appear in either\r\n"
"order.\r\n"
"When performing comparisons, the Unicode Byte Ordering Character is ignored at the\r\n"
"beginning of any argument.\r\n"
"Table 19Comparison Operators\r\n"
"Operator Definition\r\n"
"gt Greater than\r\n"
"ugt Unsigned Greater than\r\n"
"lt Less than\r\n"
"ult Unsigned Less than\r\n"
"ge Greater than or equal\r\n"
"uge Unsigned greater than or equal\r\n"
"le Less than or equal\r\n"
"ule Unsigned less than or equal\r\n"
"ne Not equal\r\n"
"eq Equals (semantically equivalent to ==)\r\n"
"== Equals (semantically equivalent to eq)\r\n"
"Error Mapping Functions\r\n"
"These functions are used to convert integers into UEFI, PI or OEM error codes, as\r\n"
"defined by Appendix D of the UEFI specification.\r\n"
"Table 20Functions used to convert integers into UEFI, PI or OEM error codes\r\n"
"Function Definition\r\n"
"UefiError Sets top nibble of parameter to 0100 binary (0x8)\r\n"
"PiError Sets top nibble of parameter to 1010 binary (0xA)\r\n"
"OemError Sets top nibble of parameter to 1100 binary (0xC)\r\n"
"Each function maps the small positive parameter into its equivalent error classification\r\n"
"as described in Appendix D of the UEFI Specification. For example,\r\n"
"...\r\n"
"if %lasterror% == EfiError(8) then # Check for write protect.\r\n"
"...\r\n"
"These functions may only be used to modify operators in comparisons.\r\n"
"Boolean Functions\r\n"
"The following built-in Boolean functions are also available:\r\n"
"Boolean Functions\r\n"
"Function Definition\r\n"
"IsInt Evaluates to true if the parameter string that follows is a number (as defined\r\n"
"below) and false otherwise.\r\n"
"Exists Evaluates to true if the file specified by string exists is in the current working\r\n"
"directory or false if not.\r\n"
"Available Evaluates to true if the file specified by string is in the current working\r\n"
"directory or current path.\r\n"
"Profile Determines whether the parameter string matches one of the profile names in\r\n"
"the profiles environment variable.\r\n"
"No spaces are allowed between function names and the open parenthesis, between\r\n"
"the open parenthesis and the string or between the string and the closed parenthesis.\r\n"
"Constant strings containing spaces must be quoted.\r\n"
"Note: To avoid ambiguity and current or future incompatibility, users are strongly\r\n"
"encouraged to surround constant strings that contain parenthesis with\r\n"
"quotes in if statements.\r\n"
"Conditional Expressions\r\n"
"Not inverts the sense of only the following expression.\r\n"
"Numbers\r\n"
"Allowable number formats are decimal numbers and C-style case insensitive\r\n"
"hexadecimal numbers. Numbers may be preceded by a "-" indicating a negative\r\n"
"number. Examples:\r\n"
""  13\r\n"
""  46\r\n"
""  -0x3FFF\r\n"
""  0x3fff\r\n"
""  0x1234\r\n"
"Unsigned values must be less than 264. Signed integer values are bounded by <00>263.\r\n"
"Numbers are internally represented in two's compliment form. The representation of\r\n"
"the number in the string has no bearing on the way that number is treated in an\r\n"
"numeric expression - type is assigned by the operator. So, for example, -1 lt 2 is\r\n"
"true but -1 ult 2 is false.\r\n"
".SH EXAMPLES\r\n"
"  #\r\n"
"  # Example script for "if" command usages 1 and 2\r\n"
"  #\r\n"
"  if exist fs0:\myscript.nsh then\r\n"
"  myscript myarg1 myarg2\r\n"
"  endif\r\n"
"  if %myvar% == runboth then\r\n"
"  myscript1\r\n"
"  myscript2\r\n"
"  else\r\n"
"  echo ^%myvar^% != runboth\r\n"
"  endif\r\n"
"In this example, if the script file myscript.nsh exists in fs0:\, this script will be launched with 2 arguments, myarg1 and myarg2. After that, environment variable %myvar% is checked to see if its value is runboth, if so, script myscript1 and myscript2 will be executed one after the other, otherwise a message %myvar% != runboth is printed.\r\n"
"  #\r\n"
"  # Example script for "if" command usage 3\r\n"
"  #\r\n"
"  :Redo\r\n"
"  echo Enter 0-6 or q to quit\r\n"
"  # assumes "input y" stores a character of user input into variable y\r\n"
"  InputCh MyVar\r\n"
"  if x%MyVar% eq x then\r\n"
"  echo Empty line. Try again\r\n"
"  goto Redo\r\n"
"  endif\r\n"
"  if IsInt(%MyVar%) and %MyVar% le 6 then\r\n"
"  myscript1 %MyVar%\r\n"
"  goto Redo\r\n"
"  endif\r\n"
"  if /i %MyVar% ne q then\r\n"
"  echo Invalid input\r\n"
"  goto Redo\r\n"
"  endif\r\n"
"In this example, the script requests user input and uses the if command for input validation. It checks for empty line first and then range checks the input. Note alsothe use of the /i in the last comparison so "Q" and "q" are both supported.\r\n"
"Note: This command does not change the value of the environment variable lasterror.\r\n"
"Note: The if command is only available in scripts.\r\n"
"Note: The else command is optional in an if/else statement.\r\n"

#string STR_GET_HELP_SHIFT        #language en-US ""
".TH shift 0 "move parameters 1 down"\r\n"
".SH NAME\r\n"
"moves all in-script parameters down 1 number (allows access over 10).\r\n"
".SH SYNOPSIS\r\n"
"shift\r\n"
".SH DESCRIPTION\r\n"
"The shift command shifts the contents of a UEFI Shell script's positional parameters so that %1 is discarded, %2 is copied to %1, %3 is copied to %2, %4 is copied to %3 and so on. This allows UEFI Shell scripts to process script parameters from left to right.\r\n"
"Note: This command does not change the UEFI shell environment variable lasterror.\r\n"
"Note: The shift command is available only in UEFI Shell scripts.\r\n"
".SH EXAMPLES\r\n"
"Following script is a sample of 'shift' command:\r\n"
"  fs0:\> type shift.nsh\r\n"
"  #\r\n"
"  # shift.nsh\r\n"
"  # \r\n"
"  echo %1 %2 %3\r\n"
"  shift\r\n"
"  echo %1 %2\r\n"
"To execute the script with echo on:\r\n"
"  fs0:\> shift.nsh welcome EFI world\r\n"
"  shift.nsh> echo welcome EFI world\r\n"
"  welcome EFI world\r\n"
"  shift\r\n"
"  echo EFI world\r\n"
"  EFI world\r\n"
"To execute the script with echo off:\r\n"
"  fs0:\> echo -off\r\n"
"  fs0:\> shift.nsh welcome EFI world\r\n"
"  welcome EFI world\r\n"
"  EFI world\r\n"

#string STR_GET_HELP_ELSE         #language en-US ""
".TH else 0 "part of an 'if' conditional statement"\r\n"
".SH NAME\r\n"
"Else identifies the portion of the code executed if the if was FALSE.\r\n"
".SH SYNOPSIS\r\n"
"else\r\n"
".SH EXAMPLES\r\n"
"See 'if'\r\n"

#string STR_GET_HELP_STALL        #language en-US ""
".TH stall 0 "stall the operation"\r\n"
".SH NAME\r\n"
"Stalls the operation for a specified number of microseconds.\r\n"
".SH SYNOPSIS\r\n"
"stall time\r\n"
".SH OPTIONS\r\n"
"time The number of microseconds for the processor to stall.\r\n"
".SH DESCRIPTION\r\n"
"This command would be used to establish a timed stall of operations during a script.\r\n"
".SH RETURNVALUES\r\n"
"SHELL_SUCCESS            The action was completed as requested.\r\n"
"SHELL_NOT_FOUND          The requested option was not found.\r\n"
"SHELL_INVALID_PARAMETER  One of the passed in parameters was incorrectly formatted or its value was out of bounds.\r\n"
"SHELL_DEVICE_ERROR	      There was a hardware error associated with this request.\r\n"